markdown-markdown 0.2.1 → 0.2.4

package/AGENT.md

@@ -24,6 +24,15 @@ For agent-facing usage guidance, use the separate [`markdown-markdown-skill`](ht
 - Run the test suite with `npm test`.
 - Publish releases through GitHub Actions on `v*` tags; avoid local `npm publish` except for bootstrap or debugging.
 
+## Async Review CLI
+
+- Prefer the async commands for agent workflows: `markdown-markdown review create`, `review wait`, `review refresh`, and `review close`.
+- `review create` starts the single active review session and opens the browser.
+- `review wait` is the source of truth for user intent. It returns either `finish_review`, `continue_review`, or an `abandoned` result.
+- If `review wait` returns `continue_review`, edit the files in the current workspace context, then run `review refresh` to start the next round.
+- If `review wait` returns `abandoned`, stop and ask the user whether to continue without review or start a fresh review session.
+- The browser UI stays readable during `awaiting_refresh`, but annotation edits are intentionally locked until the next round is ready.
+
 ## Release Workflow
 
 - Treat `main` as the source of truth.

package/README.md

@@ -2,7 +2,7 @@
 
 Local Markdown review and annotation CLI.
 
-Point it at a single Markdown file or a directory of Markdown files, make annotations in the browser, then submit once you are done. The command exits and prints a JSON payload that can be handed to an AI system or another automation step.
+Point it at a single Markdown file or a directory of Markdown files, review them in the browser, then hand the structured result back to an AI system or another automation step.
 
 ## Companion Skill
 
@@ -10,6 +10,18 @@ If you want agent instructions for using this CLI, install the separate [`markdo
 
 ## Install
 
+```bash
+npm install markdown-markdown
+```
+
+Or run it without a permanent install:
+
+```bash
+npx markdown-markdown review create --browser system ./docs/spec.md
+```
+
+## Development Setup
+
 ```bash
 npm install
 ```
@@ -34,6 +46,49 @@ The workflow uses GitHub Actions trusted publishing, so no npm token needs to be
 
 ## Use
 
+### Async review loop
+
+The primary agent-facing flow is asynchronous:
+
+```bash
+npx markdown-markdown review create --browser system ./docs/spec.md
+```
+
+`review create` starts a single active review session, opens the browser UI, and prints a JSON payload with:
+
+- `sessionId`
+- `reviewUrl`
+- `controlUrl`
+- `publicUrl`
+- `round`
+- `phase`
+
+Then the agent waits for user action:
+
+```bash
+npx markdown-markdown review wait
+```
+
+When the user clicks `Finish review`, `review wait` returns a `finish_review` payload.
+
+When the user clicks `Continue reviewing after changes`, `review wait` returns a `continue_review` payload. After the agent edits files, it should request the next round:
+
+```bash
+npx markdown-markdown review refresh
+```
+
+When the session is done, clean it up explicitly:
+
+```bash
+npx markdown-markdown review close
+```
+
+The browser UI keeps the document readable during `continue_review`, but it locks annotation edits until the next round is refreshed. The browser tab title also follows the current file name and review status, which helps when you have multiple tabs open.
+
+Markdown image assets can be local relative paths or remote URLs. Local assets are served through the review host so regular Markdown image references keep working in directory mode. Placeholder figure markers such as `![Figure 4](assets/figure-placeholder.svg)` are rendered as centered text labels instead of oversized preview art.
+
+### Legacy one-shot mode
+
 ```bash
 npx markdown-markdown ./docs
 ```
@@ -75,21 +130,23 @@ The CLI will:
 - use a public Cloudflare tunnel when `cloudflared` is installed, unless you pass `--no-cloudflare`
 - fail fast with a clear install message when you pass `--cloudflare` but `cloudflared` is missing
 - let you annotate headings, paragraphs, blockquotes, lists, tables, code blocks, images, and horizontal rules
-- submit the annotations and close the browser
-- print the final JSON result to stdout
+- support two review actions in the browser: `Finish review` and `Continue reviewing after changes`
+- print the structured review result to stdout
 - optionally write the final JSON to `--output`
 - optionally write running/completed/failed status snapshots to `--status-file`
 
 ## Output
 
-The submitted JSON includes:
+The review result JSON includes:
 
 - `rootPath`
 - `mode`
 - `files`
 - `annotations`
 - `prompt`
-- `submittedAt`
+- `submittedAt` or `abandonedAt`
+- `action` when the user submits (`finish_review` or `continue_review`)
+- `round`
 
 The `prompt` field is a ready-to-send Markdown summary of the requested changes, grouped by file with short anchor text and line ranges so an AI can locate the target block without extra token cost.
 

package/dist/cli.d.ts

@@ -8,6 +8,14 @@ export interface ParsedCliArgs {
     statusPath: string | null;
     helpRequested: boolean;
 }
+export type ReviewCommandName = 'create' | 'wait' | 'refresh' | 'close';
+export type CliInvocation = (ParsedCliArgs & {
+    kind: 'legacy';
+}) | (ParsedCliArgs & {
+    kind: 'review';
+    reviewCommand: ReviewCommandName;
+});
 export declare function parseCliArgs(argv: string[]): ParsedCliArgs;
+export declare function parseCliInvocation(argv: string[]): CliInvocation;
 export declare function isDirectExecutionEntry(argv1: string | undefined, moduleUrl: string): boolean;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,WAAW,CAAC;IACzB,cAAc,EAAE,cAAc,CAAC;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;CACxB;AA0BD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAsI1D;AAmMD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAS5F"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAuBA,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EAIf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,WAAW,CAAC;IACzB,cAAc,EAAE,cAAc,CAAC;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAExE,MAAM,MAAM,aAAa,GACrB,CAAC,aAAa,GAAG;IACf,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC,GACF,CAAC,aAAa,GAAG;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,aAAa,EAAE,iBAAiB,CAAC;CAClC,CAAC,CAAC;AAqFP,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAsI1D;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CA+BhE;AA6oBD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAS5F"}

package/dist/cli.js

@@ -1,14 +1,25 @@
 #!/usr/bin/env node
-import { existsSync, realpathSync } from 'node:fs';
-import { stat } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
+import { existsSync, realpathSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { buildCompletedStatus, buildFailedStatus, buildRunningStatus, writeJsonFile } from './lib/lifecycle.js';
 import { discoverMarkdownFiles } from './server/session.js';
 import { launchBrowser } from './server/browser.js';
 import { hasCloudflaredExecutable, launchCloudflaredTunnel } from './server/tunnel.js';
 import { startReviewRuntime } from './server/runtime.js';
+import { startReviewHost } from './server/host.js';
+import { closeSession, getActiveSession, readActiveSessionRuntime, readSessionResult, readSessionRuntime, writeSessionRuntime, } from './server/session-store.js';
+function buildCurrentCliExecArgs() {
+    const cliEntry = fileURLToPath(import.meta.url);
+    if (cliEntry.endsWith('.ts')) {
+        return ['--import', 'tsx', cliEntry];
+    }
+    return [cliEntry];
+}
 function resolveRealpath(candidate) {
     try {
         return realpathSync(candidate);
@@ -17,7 +28,7 @@ function resolveRealpath(candidate) {
         return path.resolve(candidate);
     }
 }
-function printUsage() {
+function printLegacyUsage() {
     console.error([
         'Usage: markdown-markdown [options] <file-or-directory>',
         '',
@@ -28,6 +39,29 @@ function printUsage() {
         '  --no-cloudflare             Force localhost only',
         '  --output <file>             Write the final review JSON to a file',
         '  --status-file <file>        Write running/completed status updates to a file',
+        '',
+        'Async review commands:',
+        '  markdown-markdown review create [options] <file-or-directory>',
+        '  markdown-markdown review wait',
+        '  markdown-markdown review refresh',
+        '  markdown-markdown review close',
+    ].join('\n'));
+}
+function printReviewUsage() {
+    console.error([
+        'Usage: markdown-markdown review <create|wait|refresh|close> [options]',
+        '',
+        'Commands:',
+        '  create <file-or-directory>  Start an async review session and open the browser UI',
+        '  wait                        Block until the active review session returns a result',
+        '  refresh                     Reload files for the next review round after continue_review',
+        '  close                       End the active review session and clean up the daemon',
+        '',
+        'Options for review create:',
+        '  --browser app|system        Browser launch mode (default: app)',
+        '  --cloudflare                Require a Cloudflare tunnel',
+        '  --cloudflare=auto|required|off',
+        '  --no-cloudflare             Force localhost only',
     ].join('\n'));
 }
 export function parseCliArgs(argv) {
@@ -94,7 +128,7 @@ export function parseCliArgs(argv) {
             outputPath = value;
             continue;
         }
-        if (parsingOptions && (arg === '--status-file')) {
+        if (parsingOptions && arg === '--status-file') {
             const nextValue = argv[index + 1];
             if (!nextValue) {
                 throw new Error(`Missing value for ${arg}.`);
@@ -141,6 +175,33 @@ export function parseCliArgs(argv) {
         helpRequested: false,
     };
 }
+export function parseCliInvocation(argv) {
+    if (argv[0] === 'review') {
+        const reviewCommand = argv[1];
+        if (!reviewCommand || !['create', 'wait', 'refresh', 'close'].includes(reviewCommand)) {
+            throw new Error(`Unknown review command: ${reviewCommand ?? '(missing)'}`);
+        }
+        const parsed = parseCliArgs(argv.slice(2));
+        if (reviewCommand === 'create' && !parsed.targetArg && !parsed.helpRequested) {
+            throw new Error('review create requires a file or directory target.');
+        }
+        if (reviewCommand !== 'create' && parsed.targetArg) {
+            throw new Error(`review ${reviewCommand} does not accept a target path.`);
+        }
+        if (parsed.outputPath || parsed.statusPath) {
+            throw new Error('review create/wait/refresh/close do not support --output or --status-file. Use stdout and the async commands instead.');
+        }
+        return {
+            ...parsed,
+            kind: 'review',
+            reviewCommand,
+        };
+    }
+    return {
+        ...parseCliArgs(argv),
+        kind: 'legacy',
+    };
+}
 function resolveStaticDir() {
     const scriptDir = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
@@ -155,6 +216,35 @@ function resolveStaticDir() {
     }
     return null;
 }
+async function readJsonFile(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+function sleep(milliseconds) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    });
+}
+function isPidAlive(pid) {
+    if (!pid || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function writeLifecycleArtifact(filePath, value, label) {
     if (!filePath) {
         return;
@@ -166,6 +256,75 @@ async function writeLifecycleArtifact(filePath, value, label) {
         console.error(`Failed to write ${label} at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+async function resolveTargetContext(targetArg) {
+    const targetPath = path.resolve(process.cwd(), targetArg);
+    const targetStats = await stat(targetPath).catch(() => null);
+    if (!targetStats) {
+        throw new Error(`Target path does not exist: ${targetPath}`);
+    }
+    const mode = targetStats.isFile() ? 'file' : 'directory';
+    const files = await discoverMarkdownFiles(targetPath);
+    if (files.length === 0) {
+        throw new Error(`No markdown files found under: ${targetPath}`);
+    }
+    return { files, mode, targetPath };
+}
+async function ensureNoConflictingActiveSession() {
+    const activeSession = await getActiveSession();
+    if (!activeSession) {
+        return;
+    }
+    const runtime = await readActiveSessionRuntime();
+    if (runtime && !isPidAlive(runtime.hostPid)) {
+        await closeSession(activeSession.sessionId);
+        return;
+    }
+    const location = runtime?.reviewUrl ?? runtime?.controlUrl;
+    throw new Error(`An active review session already exists: ${activeSession.sessionId}${location ? ` (${location})` : ''}. Close it before creating a new one.`);
+}
+async function waitForDaemonReady(readyFile, errorFile, childPid, timeoutMs = 20_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const errorPayload = await readJsonFile(errorFile);
+        if (errorPayload?.message) {
+            throw new Error(errorPayload.message);
+        }
+        const readyPayload = await readJsonFile(readyFile);
+        if (readyPayload) {
+            return readyPayload;
+        }
+        if (!isPidAlive(childPid)) {
+            throw new Error('Review daemon stopped before it reported a ready state.');
+        }
+        await sleep(100);
+    }
+    throw new Error('Timed out waiting for the async review daemon to start.');
+}
+function killProcessTree(pid) {
+    if (process.platform === 'win32') {
+        spawnSync('taskkill', ['/pid', String(pid), '/t', '/f'], { stdio: 'ignore' });
+        return;
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        // Ignore kill failures; close flow will fall back to clearing session state.
+    }
+}
+async function requestControl(runtime, endpoint) {
+    const response = await fetch(`${runtime.controlUrl}${endpoint}`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(body || `Control request failed: ${response.status}`);
+    }
+    return (await response.json());
+}
 async function runReviewSession(parsedArgs, targetPath, mode, files, staticDir) {
     const resolvedOutputPath = parsedArgs.outputPath ? path.resolve(process.cwd(), parsedArgs.outputPath) : null;
     const resolvedStatusPath = parsedArgs.statusPath ? path.resolve(process.cwd(), parsedArgs.statusPath) : null;
@@ -256,39 +415,307 @@ async function runReviewSession(parsedArgs, targetPath, mode, files, staticDir)
         await shutdown();
     }
 }
+function parseInternalReviewHostArgs(argv) {
+    const values = new Map();
+    for (let index = 0; index < argv.length; index += 2) {
+        const key = argv[index];
+        const value = argv[index + 1];
+        if (!key?.startsWith('--') || !value) {
+            throw new Error(`Malformed internal review host arguments near: ${key ?? '(missing)'}`);
+        }
+        values.set(key.slice(2), value);
+    }
+    const mode = values.get('mode');
+    const browserMode = values.get('browser');
+    const cloudflareMode = values.get('cloudflare');
+    if (mode !== 'file' && mode !== 'directory') {
+        throw new Error(`Unsupported internal mode: ${mode ?? '(missing)'}`);
+    }
+    if (browserMode !== 'app' && browserMode !== 'system') {
+        throw new Error(`Unsupported internal browser mode: ${browserMode ?? '(missing)'}`);
+    }
+    if (cloudflareMode !== 'auto' && cloudflareMode !== 'required' && cloudflareMode !== 'off') {
+        throw new Error(`Unsupported internal cloudflare mode: ${cloudflareMode ?? '(missing)'}`);
+    }
+    const sessionId = values.get('session-id');
+    const rootPath = values.get('root-path');
+    const staticDir = values.get('static-dir');
+    const readyFile = values.get('ready-file');
+    const errorFile = values.get('error-file');
+    if (!sessionId || !rootPath || !staticDir || !readyFile || !errorFile) {
+        throw new Error('Missing required internal review host arguments.');
+    }
+    return {
+        sessionId,
+        rootPath,
+        mode,
+        staticDir,
+        browserMode,
+        cloudflareMode,
+        readyFile,
+        errorFile,
+    };
+}
+async function writeInternalResult(filePath, payload) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+async function runInternalReviewHost(args) {
+    let browser = null;
+    let tunnel = null;
+    let host = null;
+    let shuttingDown = false;
+    let shutdownResolver = null;
+    const shutdown = async () => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        await browser?.close();
+        await tunnel?.close();
+        await host?.close();
+        shutdownResolver?.();
+    };
+    try {
+        const files = await discoverMarkdownFiles(args.rootPath);
+        host = await startReviewHost({
+            files,
+            mode: args.mode,
+            rootPath: args.rootPath,
+            sessionId: args.sessionId,
+            staticDir: args.staticDir,
+        });
+        if (args.cloudflareMode === 'required' && !hasCloudflaredExecutable()) {
+            throw new Error('Cloudflare tunnel was requested, but cloudflared is not installed. Install cloudflared or rerun with --no-cloudflare.');
+        }
+        if (args.cloudflareMode !== 'off') {
+            tunnel = await launchCloudflaredTunnel(host.url);
+            if (args.cloudflareMode === 'required' && !tunnel) {
+                throw new Error('Cloudflare tunnel was requested, but cloudflared could not start. Install cloudflared or rerun with --no-cloudflare.');
+            }
+        }
+        const launchUrl = tunnel?.publicUrl ?? host.url;
+        browser =
+            args.browserMode === 'system'
+                ? await launchBrowser(launchUrl, { executableCandidates: [] })
+                : await launchBrowser(launchUrl);
+        if (browser.process) {
+            browser.process.once('exit', () => {
+                void host?.notifyBrowserClosed();
+            });
+        }
+        await writeSessionRuntime(host.sessionId, {
+            browserMode: args.browserMode,
+            cloudflareMode: args.cloudflareMode,
+            controlUrl: host.url,
+            hostPid: process.pid,
+            publicUrl: tunnel?.publicUrl ?? null,
+            reviewUrl: launchUrl,
+            startedAt: new Date().toISOString(),
+        });
+        await writeInternalResult(args.readyFile, {
+            browserMode: args.browserMode,
+            cloudflareMode: args.cloudflareMode,
+            controlUrl: host.url,
+            mode: args.mode,
+            phase: 'waiting_for_review',
+            publicUrl: tunnel?.publicUrl ?? null,
+            reviewUrl: launchUrl,
+            rootPath: args.rootPath,
+            round: 1,
+            sessionId: host.sessionId,
+        });
+        host.result.then(async (result) => {
+            if ('action' in result && result.action === 'finish_review') {
+                await browser?.close();
+            }
+        }).catch(() => {
+            // Errors are surfaced to control commands and stderr; keep the daemon alive for inspection.
+        });
+        process.once('SIGINT', () => {
+            void shutdown();
+        });
+        process.once('SIGTERM', () => {
+            void shutdown();
+        });
+        process.once('uncaughtException', (error) => {
+            void writeInternalResult(args.errorFile, {
+                message: error instanceof Error ? error.message : String(error),
+            }).finally(() => shutdown());
+        });
+        await new Promise((resolve) => {
+            shutdownResolver = resolve;
+        });
+    }
+    catch (error) {
+        await writeInternalResult(args.errorFile, {
+            message: error instanceof Error ? error.message : String(error),
+        });
+        await shutdown();
+        throw error;
+    }
+}
+async function runReviewCreate(parsed) {
+    await ensureNoConflictingActiveSession();
+    const staticDir = resolveStaticDir();
+    if (!staticDir) {
+        throw new Error('Build output not found. Run the package build before starting the CLI.');
+    }
+    const { mode, targetPath } = await resolveTargetContext(parsed.targetArg ?? '');
+    const tempDir = await mkdtemp(path.join(tmpdir(), 'markdown-markdown-daemon-'));
+    const readyFile = path.join(tempDir, 'ready.json');
+    const errorFile = path.join(tempDir, 'error.json');
+    const sessionId = randomUUID();
+    const child = spawn(process.execPath, [
+        ...buildCurrentCliExecArgs(),
+        '__internal-review-host',
+        '--session-id',
+        sessionId,
+        '--root-path',
+        targetPath,
+        '--mode',
+        mode,
+        '--browser',
+        parsed.browserMode,
+        '--cloudflare',
+        parsed.cloudflareMode,
+        '--static-dir',
+        staticDir,
+        '--ready-file',
+        readyFile,
+        '--error-file',
+        errorFile,
+    ], {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+    try {
+        const ready = await waitForDaemonReady(readyFile, errorFile, child.pid ?? 0);
+        process.stdout.write(`${JSON.stringify(ready, null, 2)}\n`);
+    }
+    finally {
+        await rm(tempDir, { force: true, recursive: true });
+    }
+}
+async function runReviewWait() {
+    const activeSession = await getActiveSession();
+    if (!activeSession) {
+        throw new Error('No active review session is running.');
+    }
+    while (true) {
+        const result = await readSessionResult(activeSession.sessionId);
+        if (result) {
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            return;
+        }
+        const runtime = await readSessionRuntime(activeSession.sessionId);
+        if (runtime && !isPidAlive(runtime.hostPid)) {
+            throw new Error('The active review daemon stopped before producing a result.');
+        }
+        await sleep(500);
+    }
+}
+async function requireActiveRuntime() {
+    const activeSession = await getActiveSession();
+    if (!activeSession) {
+        throw new Error('No active review session is running.');
+    }
+    const runtime = await readSessionRuntime(activeSession.sessionId);
+    if (!runtime) {
+        throw new Error(`Runtime metadata for active review session ${activeSession.sessionId} is missing.`);
+    }
+    return {
+        runtime,
+        sessionId: activeSession.sessionId,
+    };
+}
+async function runReviewRefresh() {
+    const { runtime } = await requireActiveRuntime();
+    const refreshed = await requestControl(runtime, '/api/control/refresh');
+    process.stdout.write(`${JSON.stringify(refreshed, null, 2)}\n`);
+}
+async function runReviewClose() {
+    const activeSession = await getActiveSession();
+    if (!activeSession) {
+        process.stdout.write(`${JSON.stringify({ closed: false, reason: 'no_active_session' }, null, 2)}\n`);
+        return;
+    }
+    const runtime = await readSessionRuntime(activeSession.sessionId);
+    if (runtime) {
+        try {
+            await requestControl(runtime, '/api/control/close');
+        }
+        catch {
+            // Fall through to the process kill and state cleanup path.
+        }
+        if (isPidAlive(runtime.hostPid)) {
+            killProcessTree(runtime.hostPid);
+        }
+    }
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        const current = await getActiveSession();
+        if (!current) {
+            process.stdout.write(`${JSON.stringify({ closed: true, sessionId: activeSession.sessionId }, null, 2)}\n`);
+            return;
+        }
+        await sleep(100);
+    }
+    await closeSession(activeSession.sessionId);
+    process.stdout.write(`${JSON.stringify({ closed: true, forced: true, sessionId: activeSession.sessionId }, null, 2)}\n`);
+}
 async function main() {
-    let parsedArgs;
+    if (process.argv[2] === '__internal-review-host') {
+        const args = parseInternalReviewHostArgs(process.argv.slice(3));
+        await runInternalReviewHost(args);
+        return;
+    }
+    let invocation;
     try {
-        parsedArgs = parseCliArgs(process.argv.slice(2));
+        invocation = parseCliInvocation(process.argv.slice(2));
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
-        printUsage();
+        printLegacyUsage();
         process.exit(1);
     }
-    if (parsedArgs.helpRequested) {
-        printUsage();
+    if (invocation.helpRequested) {
+        if (invocation.kind === 'review') {
+            printReviewUsage();
+        }
+        else {
+            printLegacyUsage();
+        }
         process.exit(0);
     }
-    if (!parsedArgs.targetArg) {
-        printUsage();
-        process.exit(1);
-    }
-    const targetPath = path.resolve(process.cwd(), parsedArgs.targetArg);
-    const targetStats = await stat(targetPath).catch(() => null);
-    if (!targetStats) {
-        throw new Error(`Target path does not exist: ${targetPath}`);
+    if (invocation.kind === 'review') {
+        switch (invocation.reviewCommand) {
+            case 'create':
+                await runReviewCreate(invocation);
+                return;
+            case 'wait':
+                await runReviewWait();
+                return;
+            case 'refresh':
+                await runReviewRefresh();
+                return;
+            case 'close':
+                await runReviewClose();
+                return;
+            default:
+                throw new Error(`Unsupported review command: ${String(invocation.reviewCommand)}`);
+        }
     }
-    const mode = targetStats.isFile() ? 'file' : 'directory';
-    const files = await discoverMarkdownFiles(targetPath);
-    if (files.length === 0) {
-        throw new Error(`No markdown files found under: ${targetPath}`);
+    if (!invocation.targetArg) {
+        printLegacyUsage();
+        process.exit(1);
     }
+    const { files, mode, targetPath } = await resolveTargetContext(invocation.targetArg);
     const staticDir = resolveStaticDir();
     if (!staticDir) {
         throw new Error('Build output not found. Run the package build before starting the CLI.');
     }
-    await runReviewSession(parsedArgs, targetPath, mode, files, staticDir);
+    await runReviewSession(invocation, targetPath, mode, files, staticDir);
 }
 export function isDirectExecutionEntry(argv1, moduleUrl) {
     if (!argv1) {